abstractnote 0.1.0__py3-none-any.whl

abstractnote/tools/__init__.py

@@ -0,0 +1,215 @@
+"""Note tools: plane-bound callables for flows (``tool_calls`` nodes) and agents (``allowed_tools``).
+
+``bind(notebook_dir, ...)`` returns ``{tool_name: callable}``; each callable is
+decorated with AbstractCore's ``@tool``, so ``MappingToolExecutor.from_tools``
+and the runtime's ``tool_calls`` nodes use them directly and their
+``ToolDefinition.parameters`` describe the accepted arguments. Every tool takes
+JSON-friendly keyword arguments, returns a dict, and raises ``ValueError`` with
+a plain sentence on bad input. ``TOOL_NAMES`` is the auto-approve list.
+
+The notebook is opened on the first call, so binding is cheap and creates no
+files.
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from .context import ArtifactReader, ToolContext
+
+TOOL_NAMES: List[str] = [
+    "note_capture", "note_file", "note_context", "note_resolve_candidates", "note_apply_revision",
+    "note_queue_lease", "note_queue_ack", "note_queue_stats", "note_search", "note_expand",
+    "note_changes", "note_entity", "note_timeline", "note_open_loops", "note_contradictions",
+    "note_resurface", "note_anniversaries", "note_insight_write",
+]
+
+
+class _LazyContext(ToolContext):
+    """A ToolContext whose notebook opens on first use."""
+
+    def __init__(self, notebook_dir: Path, embedder: Any, **kwargs: Any) -> None:
+        super().__init__(nb=None, **kwargs)
+        self._dir = Path(notebook_dir)
+        self._embedder = embedder
+        self._open_lock = threading.Lock()
+
+    def __getattribute__(self, name: str) -> Any:
+        if name == "nb":
+            nb = object.__getattribute__(self, "__dict__").get("nb")
+            if nb is None:
+                with object.__getattribute__(self, "_open_lock"):
+                    nb = object.__getattribute__(self, "__dict__").get("nb")
+                    if nb is None:
+                        from ..store.notebook import Notebook
+
+                        nb = Notebook.open(object.__getattribute__(self, "_dir"),
+                                           embedder=object.__getattribute__(self, "_embedder"))
+                        nb.extractors.update(object.__getattribute__(self, "extractors"))
+                        object.__getattribute__(self, "__dict__")["nb"] = nb
+            return nb
+        return object.__getattribute__(self, name)
+
+
+def bind(notebook_dir: "str | Path", *, embedder: Any = None, artifact_reader: Optional[ArtifactReader] = None,
+         extractors: Optional[Dict[str, Any]] = None, allow_paths_under: "str | Path | None" = None,
+         account: Optional[str] = None, default_client: str = "agent") -> Dict[str, Callable[..., Any]]:
+    """The note tools bound to one notebook directory.
+
+    - ``embedder``: the notebook's embedding model (None keeps the notebook's own pin).
+    - ``artifact_reader(ref) -> (bytes, mime, filename)``: resolves ``{"$artifact": id}`` attachments.
+    - ``extractors``: ``{"vision": fn, "stt": fn}`` for image descriptions and transcripts.
+    - ``allow_paths_under``: accept ``{"path": ...}`` attachments inside this folder (headless only).
+    - ``account``: stamped as ``source.account`` on every captured note.
+    """
+    from abstractcore.tools.core import tool
+
+    from . import capture as cap
+    from . import process as proc
+    from . import queue as que
+    from . import recall as rec
+
+    ctx = _LazyContext(Path(notebook_dir).expanduser(), embedder, artifact_reader=artifact_reader,
+                       allow_paths_under=Path(allow_paths_under).expanduser() if allow_paths_under else None,
+                       account=account, default_client=default_client, extractors=dict(extractors or {}))
+
+    @tool(name="note_capture", description="Save a note (text, time, place, attachments) to the notebook now.",
+          when_to_use="Whenever something should be remembered; returns the note id, revisits and similar notes.")
+    def note_capture(text: str = "", idempotency_key: Optional[str] = None, title: Optional[str] = None,
+                     occurred_at: Optional[str] = None, location: Optional[Dict[str, Any]] = None,
+                     source: Optional[Dict[str, Any]] = None, priority: Optional[int] = None,
+                     attachments: Optional[List[Dict[str, Any]]] = None, session_id: Optional[str] = None,
+                     about: Optional[Dict[str, Any]] = None, answer: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Save a note to the notebook now (``answer`` = {question, evidence_note_ids}: a saved answer)."""
+        return cap.note_capture(ctx, text, idempotency_key, title, occurred_at, location, source, priority,
+                                attachments, session_id, about, answer)
+
+    @tool(name="note_file", description="Store the quick filing of a note: title, kind, topics, urgency, language.")
+    def note_file(note_id: str, title: Optional[str] = None, kind: Optional[str] = None,
+                  topics: Optional[List[str]] = None, urgency: Optional[str] = None, language: Optional[str] = None,
+                  one_line: Optional[str] = None) -> Dict[str, Any]:
+        """Store the quick filing of a note."""
+        return cap.note_file(ctx, note_id, title, kind, topics, urgency, language, one_line)
+
+    @tool(name="note_context", description="What the notebook already knows that is relevant to one note.",
+          when_to_use="First step of processing a note: sections, similar notes, candidate entities, open tasks.")
+    def note_context(note_id: str, max_chars: Optional[int] = None) -> Dict[str, Any]:
+        """What the notebook already knows that is relevant to one note."""
+        return proc.note_context(ctx, note_id, max_chars)
+
+    @tool(name="note_resolve_candidates", description="Existing entities that each mention of a note may refer to.")
+    def note_resolve_candidates(note_id: str, mentions: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Existing entities that each mention may refer to."""
+        return proc.note_resolve_candidates(ctx, note_id, mentions)
+
+    @tool(name="note_apply_revision", description="Apply the extraction and linking decisions of a note to the graph.")
+    def note_apply_revision(note_id: str, extraction: Dict[str, Any], linking: Dict[str, Any]) -> Dict[str, Any]:
+        """Apply the extraction and linking decisions of a note to the graph."""
+        return proc.note_apply_revision(ctx, note_id, extraction, linking)
+
+    @tool(name="note_queue_lease", description="Take the next notes to process from the queue, by priority.")
+    def note_queue_lease(worker_id: str, max_items: int = 1) -> Dict[str, Any]:
+        """Take the next notes to process from the queue."""
+        return que.note_queue_lease(ctx, worker_id, max_items)
+
+    @tool(name="note_queue_ack", description="Report how processing a leased note went (ok or error).")
+    def note_queue_ack(note_id: str, outcome: str, error: Optional[str] = None,
+                       revision_id: Optional[str] = None) -> Dict[str, Any]:
+        """Report how processing a leased note went."""
+        return que.note_queue_ack(ctx, note_id, outcome, error or None, revision_id or None)
+
+    @tool(name="note_queue_stats", description="How many notes wait, are being processed or failed.")
+    def note_queue_stats() -> Dict[str, Any]:
+        """How many notes wait, are being processed or failed."""
+        return que.note_queue_stats(ctx)
+
+    @tool(name="note_search", description="Quick search of the notes, entities and statements (no model).",
+          when_to_use="Before a task or to answer a question cheaply; filters by time, kind, entity and topic.")
+    def note_search(query: str = "", since: Optional[str] = None, until: Optional[str] = None,
+                    kinds: Optional[List[str]] = None, entities: Optional[List[str]] = None,
+                    topics: Optional[List[str]] = None, limit: int = 20, as_of: Optional[str] = None
+                    ) -> Dict[str, Any]:
+        """Quick search of the notes, entities and statements."""
+        return rec.note_search(ctx, query, since, until, kinds, entities, topics, limit, as_of)
+
+    @tool(name="note_expand", description="Entity cards, timelines, relations and then-versus-now around notes or entities.")
+    def note_expand(note_ids: Optional[List[str]] = None, entity_ids: Optional[List[str]] = None,
+                    as_of: Optional[str] = None) -> Dict[str, Any]:
+        """Entity cards, timelines, relations and then-versus-now around notes or entities."""
+        return rec.note_expand(ctx, note_ids, entity_ids, as_of)
+
+    @tool(name="note_changes", description="What the notebook learned since a cursor or a time.",
+          when_to_use="First call of a session: new notes and entities, superseded beliefs, closed loops, failures.")
+    def note_changes(since: Optional[str] = None, limit: int = 50) -> Dict[str, Any]:
+        """What the notebook learned since a cursor or a time."""
+        return rec.note_changes(ctx, since, limit)
+
+    @tool(name="note_entity", description="The card of one entity as known at a moment.")
+    def note_entity(entity_id: str, at: Optional[str] = None) -> Dict[str, Any]:
+        """The card of one entity as known at a moment."""
+        return rec.note_entity(ctx, entity_id, at)
+
+    @tool(name="note_timeline", description="Notebook activity per day, week or month.")
+    def note_timeline(since: Optional[str] = None, until: Optional[str] = None,
+                      granularity: str = "day") -> Dict[str, Any]:
+        """Notebook activity per day, week or month."""
+        return rec.note_timeline(ctx, since, until, granularity)
+
+    @tool(name="note_open_loops", description="Open tasks and unanswered questions that may need attention.")
+    def note_open_loops(limit: int = 20, since: Optional[str] = None) -> Dict[str, Any]:
+        """Open tasks and unanswered questions."""
+        return rec.note_open_loops(ctx, limit, since)
+
+    @tool(name="note_contradictions", description="Disputed statements and subjects with several current values.")
+    def note_contradictions(limit: int = 20, since: Optional[str] = None) -> Dict[str, Any]:
+        """Disputed statements and subjects with several current values."""
+        return rec.note_contradictions(ctx, limit, since)
+
+    @tool(name="note_resurface", description="Entities and topics gone quiet that relate to recent notes.")
+    def note_resurface(limit: int = 20, since: Optional[str] = None) -> Dict[str, Any]:
+        """Entities and topics gone quiet that relate to recent notes."""
+        return rec.note_resurface(ctx, limit, since)
+
+    @tool(name="note_anniversaries", description="Notes from this day in earlier months and years.")
+    def note_anniversaries(limit: int = 20, since: Optional[str] = None) -> Dict[str, Any]:
+        """Notes from this day in earlier months and years."""
+        return rec.note_anniversaries(ctx, limit, since)
+
+    @tool(name="note_insight_write", description="Store an insight or a dossier with the notes and entities behind it.")
+    def note_insight_write(kind: str, title: str, body: str, evidence_note_ids: Optional[List[str]] = None,
+                           entity_ids: Optional[List[str]] = None, run_id: Optional[str] = None) -> Dict[str, Any]:
+        """Store an insight or a dossier with its evidence."""
+        return rec.note_insight_write(ctx, kind, title, body, evidence_note_ids, entity_ids, run_id)
+
+    tools = {
+        "note_capture": note_capture, "note_file": note_file, "note_context": note_context,
+        "note_resolve_candidates": note_resolve_candidates, "note_apply_revision": note_apply_revision,
+        "note_queue_lease": note_queue_lease, "note_queue_ack": note_queue_ack, "note_queue_stats": note_queue_stats,
+        "note_search": note_search, "note_expand": note_expand, "note_changes": note_changes,
+        "note_entity": note_entity, "note_timeline": note_timeline, "note_open_loops": note_open_loops,
+        "note_contradictions": note_contradictions, "note_resurface": note_resurface,
+        "note_anniversaries": note_anniversaries, "note_insight_write": note_insight_write,
+    }
+    assert list(tools) == TOOL_NAMES
+    return tools
+
+
+def bound_notebook(tools: Dict[str, Callable[..., Any]]) -> Any:
+    """The Notebook behind a bound tool set (opens it when needed)."""
+    fn = tools["note_search"]
+    for cell in getattr(fn, "__closure__", None) or ():
+        value = cell.cell_contents
+        if isinstance(value, ToolContext):
+            return value.nb
+    raise ValueError("These tools were not made by abstractnote.tools.bind.")
+
+
+def tool_specs() -> List[Dict[str, Any]]:
+    """The LLM-facing specs of the note tools (for ``llm_call.tools`` or an agent's catalog)."""
+    tools = bind(Path("/nonexistent-abstractnote-spec-only"))  # never opened: specs only
+    return [tools[name]._tool_definition.to_dict() for name in TOOL_NAMES]
+
+
+__all__ = ["TOOL_NAMES", "ToolContext", "bind", "bound_notebook", "tool_specs"]

abstractnote/tools/capture.py

@@ -0,0 +1,121 @@
+"""``note_capture`` and ``note_file`` (docs/api.md, "Note tools").
+
+Attachments are ``{"$artifact": id, "run_id"?: ...}`` gateway references,
+resolved through the injected ``artifact_reader(ref) -> (bytes, mime,
+filename)``, or ``{"path": ...}`` local files, accepted only when the tools
+were bound with ``allow_paths_under=ROOT`` and the resolved path is inside it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .context import ToolContext
+
+
+def resolve_attachments(ctx: ToolContext, attachments: Optional[List[Any]]) -> List[Dict[str, Any]]:
+    out: List[Dict[str, Any]] = []
+    for i, item in enumerate(attachments or []):
+        if not isinstance(item, dict):
+            raise ValueError(f"Attachment {i + 1} must be an object with $artifact or path.")
+        if "$artifact" in item:
+            ref = {"$artifact": str(item["$artifact"])}
+            if item.get("run_id"):
+                ref["run_id"] = str(item["run_id"])
+            if ctx.artifact_reader is None:
+                raise ValueError("This notebook cannot read gateway attachments: no artifact reader was bound to "
+                                 "the note tools (abstractnote.tools.bind(..., artifact_reader=...)).")
+            data, mime, filename = ctx.artifact_reader(ref)
+            if not isinstance(data, (bytes, bytearray)):
+                raise ValueError(f"The attachment {ref['$artifact']} could not be read.")
+            out.append({"data": bytes(data), "mime": item.get("mime") or mime,
+                        "filename": item.get("filename") or filename,
+                        "artifact_ref": {"artifact_id": ref["$artifact"], **({"run_id": ref["run_id"]}
+                                                                             if "run_id" in ref else {})}})
+        elif "path" in item:
+            if ctx.allow_paths_under is None:
+                raise ValueError("Local file paths are not accepted here; upload the file as an attachment instead.")
+            root = Path(ctx.allow_paths_under).expanduser().resolve()
+            path = Path(str(item["path"])).expanduser()
+            if not path.is_absolute():
+                path = root / path
+            path = path.resolve()
+            if path != root and root not in path.parents:
+                raise ValueError("That file is outside the folder this notebook may read from.")
+            if not path.is_file():
+                raise ValueError(f"There is no file at {item['path']}.")
+            out.append({"data": path.read_bytes(), "mime": item.get("mime"), "filename": item.get("filename") or path.name,
+                        "artifact_ref": None})
+        else:
+            raise ValueError(f"Attachment {i + 1} must have $artifact (or path when reading local files is allowed).")
+    return out
+
+
+def note_capture(ctx: ToolContext, text: str = "", idempotency_key: Optional[str] = None, title: Optional[str] = None,
+                 occurred_at: Optional[str] = None, location: Optional[Dict[str, Any]] = None,
+                 source: Optional[Dict[str, Any]] = None, priority: Optional[int] = None,
+                 attachments: Optional[List[Any]] = None, session_id: Optional[str] = None,
+                 about: Optional[Dict[str, Any]] = None, answer: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    def blank(v: Any) -> Any:  # flows pass "" / {} / [] for unset start pins
+        return None if v in ("", {}, []) else v
+
+    saved_answer = _answer(blank(answer))
+    resolved = resolve_attachments(ctx, blank(attachments))
+    priority = blank(priority)
+    result = ctx.nb.capture(
+        text, title=blank(title), occurred_at=blank(occurred_at), location=blank(location), source=blank(source),
+        priority=None if priority is None else int(priority), attachments=resolved,
+        idempotency_key=blank(idempotency_key), session_id=blank(session_id), account=ctx.account, about=blank(about),
+        default_client=ctx.default_client, vision=ctx.extractors.get("vision"), stt=ctx.extractors.get("stt"),
+    )
+    out = result.model_dump()
+    if saved_answer is not None and result.status == "new":
+        out["warnings"] = list(out.get("warnings") or []) + _file_answer(ctx.nb, result.note_id, saved_answer)
+    return out
+
+
+def _answer(answer: Any) -> Optional[Dict[str, Any]]:
+    """``context.answer = {question, evidence_note_ids}`` (the web app's "Save this answer"), checked."""
+    if answer is None:
+        return None
+    if not isinstance(answer, dict) or not str(answer.get("question") or "").strip():
+        raise ValueError("A saved answer needs the question it answers.")
+    evidence = answer.get("evidence_note_ids") or []
+    if not isinstance(evidence, list) or not all(isinstance(x, str) for x in evidence):
+        raise ValueError("The evidence of a saved answer must be a list of note ids.")
+    return {"question": str(answer["question"]).strip(), "evidence_note_ids": list(dict.fromkeys(evidence))}
+
+
+def _file_answer(nb: Any, note_id: str, answer: Dict[str, Any]) -> List[str]:
+    """File a saved answer as a ``synthesis`` note linked (``dcterms:references``) to each evidence
+    note, the same link ``context.about`` makes; evidence ids outside the notebook are left out."""
+    from .. import ids
+    from ..store.notes import _j
+
+    warnings: List[str] = []
+    now = ids.utc_now()
+    detail = _j({"kind": "answer", "question": answer["question"]})
+    with nb.store.tx() as c:
+        c.execute("UPDATE notes SET kind='synthesis' WHERE note_id=?", (note_id,))
+        for nid in answer["evidence_note_ids"]:
+            if nid == note_id or nb.store.note_row(nid) is None:
+                warnings.append(f"The evidence note {nid} is not in this notebook; it was left out.")
+                continue
+            c.execute("INSERT OR IGNORE INTO note_links(src_note_id, dst_note_id, predicate, score, matched_by,"
+                      " detail_json, created_at) VALUES (?,?,?,1.0,?,?,?)",
+                      (note_id, nid, "dcterms:references", "answer", detail, now))
+    return warnings
+
+
+def note_file(ctx: ToolContext, note_id: str, title: Optional[str] = None, kind: Optional[str] = None,
+              topics: Optional[List[str]] = None, urgency: Optional[str] = None, language: Optional[str] = None,
+              one_line: Optional[str] = None) -> Dict[str, Any]:
+    def blank(v: Any) -> Any:
+        return None if v in ("", {}, []) else v
+
+    row = ctx.nb.store.note_row(note_id)
+    if row is not None and row["kind"] == "synthesis":
+        kind = None  # a saved answer stays a synthesis whatever the quick filing proposes
+    return ctx.nb.file_note(note_id, title=blank(title), kind=blank(kind), topics=topics or [],
+                            urgency=blank(urgency), language=blank(language), one_line=blank(one_line))

abstractnote/tools/context.py

@@ -0,0 +1,19 @@
+"""What a bound tool set knows: the notebook, the injected readers and the account."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Tuple
+
+ArtifactReader = Callable[[Dict[str, Any]], Tuple[bytes, Optional[str], Optional[str]]]
+
+
+@dataclass
+class ToolContext:
+    nb: Any  # abstractnote.store.notebook.Notebook
+    artifact_reader: Optional[ArtifactReader] = None
+    allow_paths_under: Optional[Path] = None
+    account: Optional[str] = None
+    default_client: str = "agent"
+    extractors: Dict[str, Any] = field(default_factory=dict)

abstractnote/tools/process.py

@@ -0,0 +1,22 @@
+"""``note_context``, ``note_resolve_candidates``, ``note_apply_revision`` (docs/api.md)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..process.context import note_context as _context
+from ..process.resolve import resolve_candidates
+from ..process.revise import apply_note_revision
+from .context import ToolContext
+
+
+def note_context(ctx: ToolContext, note_id: str, max_chars: Optional[int] = None) -> Dict[str, Any]:
+    return _context(ctx.nb, note_id, max_chars)
+
+
+def note_resolve_candidates(ctx: ToolContext, note_id: str, mentions: List[Dict[str, Any]]) -> Dict[str, Any]:
+    return resolve_candidates(ctx.nb, note_id, mentions)
+
+
+def note_apply_revision(ctx: ToolContext, note_id: str, extraction: Any, linking: Dict[str, Any]) -> Dict[str, Any]:
+    return apply_note_revision(ctx.nb, note_id, extraction, linking)

abstractnote/tools/queue.py

@@ -0,0 +1,23 @@
+"""``note_queue_lease``, ``note_queue_ack``, ``note_queue_stats`` (docs/api.md)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .context import ToolContext
+
+
+def note_queue_lease(ctx: ToolContext, worker_id: str, max_items: int = 1) -> Dict[str, Any]:
+    out = ctx.nb.queue.lease(worker_id, max_items)
+    return {"items": [{"note_id": i["note_id"], "priority": i["priority"], "attempts": i["attempts"]}
+                      for i in out["items"]]}
+
+
+def note_queue_ack(ctx: ToolContext, note_id: str, outcome: str, error: Optional[str] = None,
+                   revision_id: Optional[str] = None) -> Dict[str, Any]:
+    return ctx.nb.queue.ack(note_id, outcome, error=error, revision_id=revision_id)
+
+
+def note_queue_stats(ctx: ToolContext) -> Dict[str, Any]:
+    stats = ctx.nb.queue.stats()
+    return {k: stats[k] for k in ("queued", "processing", "failed", "by_priority", "oldest_enqueued_at")}

abstractnote/tools/recall.py

@@ -0,0 +1,64 @@
+"""Recall and reflect tools (docs/api.md): note_search, note_expand, note_changes, note_entity,
+note_timeline, note_open_loops, note_contradictions, note_resurface, note_anniversaries,
+note_insight_write."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..recall import expand as _expand
+from ..recall import reflect as _reflect
+from ..recall.insights import write_insight
+from ..recall.search import search
+from .context import ToolContext
+
+
+def _blank(v: Any) -> Any:
+    return None if v in ("", {}, []) else v
+
+
+def note_search(ctx: ToolContext, query: str = "", since: Optional[str] = None, until: Optional[str] = None,
+                kinds: Optional[List[str]] = None, entities: Optional[List[str]] = None,
+                topics: Optional[List[str]] = None, limit: int = 20, as_of: Optional[str] = None) -> Dict[str, Any]:
+    return search(ctx.nb, query or "", since=_blank(since), until=_blank(until), kinds=_blank(kinds),
+                  entities=_blank(entities), topics=_blank(topics), limit=int(limit or 20), as_of=_blank(as_of))
+
+
+def note_expand(ctx: ToolContext, note_ids: Optional[List[str]] = None, entity_ids: Optional[List[str]] = None,
+                as_of: Optional[str] = None) -> Dict[str, Any]:
+    return _expand.expand(ctx.nb, note_ids or [], entity_ids or [], _blank(as_of))
+
+
+def note_changes(ctx: ToolContext, since: Optional[str] = None, limit: int = 50) -> Dict[str, Any]:
+    return ctx.nb.changes(_blank(since), int(limit or 50))
+
+
+def note_entity(ctx: ToolContext, entity_id: str, at: Optional[str] = None) -> Dict[str, Any]:
+    return _expand.entity_card(ctx.nb, entity_id, _blank(at))
+
+
+def note_timeline(ctx: ToolContext, since: Optional[str] = None, until: Optional[str] = None,
+                  granularity: str = "day") -> Dict[str, Any]:
+    return ctx.nb.timeline(_blank(since), _blank(until), granularity or "day")
+
+
+def note_open_loops(ctx: ToolContext, limit: int = 20, since: Optional[str] = None) -> Dict[str, Any]:
+    return _reflect.open_loops(ctx.nb, int(limit or 20), _blank(since))
+
+
+def note_contradictions(ctx: ToolContext, limit: int = 20, since: Optional[str] = None) -> Dict[str, Any]:
+    return _reflect.contradictions(ctx.nb, int(limit or 20), _blank(since))
+
+
+def note_resurface(ctx: ToolContext, limit: int = 20, since: Optional[str] = None) -> Dict[str, Any]:
+    return _reflect.resurface(ctx.nb, int(limit or 20), _blank(since))
+
+
+def note_anniversaries(ctx: ToolContext, limit: int = 20, since: Optional[str] = None) -> Dict[str, Any]:
+    return _reflect.anniversaries(ctx.nb, int(limit or 20), _blank(since))
+
+
+def note_insight_write(ctx: ToolContext, kind: str, title: str, body: str,
+                       evidence_note_ids: Optional[List[str]] = None, entity_ids: Optional[List[str]] = None,
+                       run_id: Optional[str] = None) -> Dict[str, Any]:
+    return write_insight(ctx.nb, kind, title, body, evidence_note_ids or [], entity_ids or [], _blank(run_id))

abstractnote-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: abstractnote
+Version: 0.1.0
+Summary: AbstractNote: one endpoint for your notes; a temporal semantic knowledge graph of your life, built on AbstractGateway, AbstractRuntime and AbstractMemory
+Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/lpalbou/abstractnote
+Project-URL: Repository, https://github.com/lpalbou/abstractnote
+Project-URL: Issues, https://github.com/lpalbou/abstractnote/issues
+Keywords: notes,knowledge-graph,memory,temporal,abstractframework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: abstractmemory>=0.3.1
+Requires-Dist: abstractsemantics>=0.0.5
+Requires-Dist: abstractruntime>=0.10.2
+Requires-Dist: abstractcore>=2.26.3
+Requires-Dist: pydantic>=2.0
+Provides-Extra: gateway
+Requires-Dist: abstractgateway>=0.15.11; extra == "gateway"
+Requires-Dist: fastapi>=0.110; extra == "gateway"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+# AbstractNote
+
+One endpoint for everything you want to remember. Send a sentence, a document, a photo, a
+recording, a log. AbstractNote files it with its time, place and provenance, links it to what
+you already know, and grows a **temporal semantic knowledge graph** of your ideas, projects,
+people and decisions. You search it by effort (quick, standard, deep) and revisit it through
+time: what you knew, when you learned it, and how your view changed.
+
+AbstractNote is part of the AbstractFramework. It runs on **AbstractGateway** (sign-in, one
+runtime and one notebook per user, app hosting), **AbstractRuntime** and **AbstractFlow** (the
+capture and understanding workflows), **AbstractMemory** (temporal facts) and **AbstractCore**
+(models, structured output, embeddings).
+
+Status: version 0.1.0, in development. It is not published on PyPI or npm yet; you install it
+from source (see [Install](#install)).
+
+## What you get
+
+- **Capture anywhere**: the web app, the Apple Watch app, the `abstractnote` command line, and
+  agents. Attachments are de-duplicated by content; a retried send never saves a note twice.
+- **Automatic filing**: a small fast model gives each note a title, a kind, topics, an urgency
+  and its language, next to the time and place it was made.
+- **Self-organising knowledge**: a model resolves people, projects and ideas against candidates
+  that exact lookups, full-text and vectors produce. Every change is a revision you can replay,
+  and every claim keeps the note it came from.
+- **Remember by cue and effort**: quick (no model, under a second), standard (one synthesis with
+  citations), deep (a background dossier). Then-versus-now for any person, project, idea or link.
+- **Reflection**: open loops, contradictions, things that went quiet and connections you may have
+  missed, surfaced as insights.
+- **Imports**: Claude Code sessions, an agora hub database, Markdown trees and plain files, with
+  their original dates and provenance.
+
+## Install
+
+AbstractNote needs Python 3.10 or later and the framework packages next to it. Until the
+packages are published, install everything from source checkouts:
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -e ../abstractsemantics -e ../abstractcore -e ../abstractruntime \
+                      -e ../abstractmemory     # a checkout that has close_assertion, see below
+.venv/bin/pip install -e .
+.venv/bin/abstractnote --help
+```
+
+Two framework changes that AbstractNote relies on are not in released packages yet:
+
+- **AbstractMemory `close_assertion`** (the `close-assertion` branch): closes a superseded fact in
+  place. AbstractNote's first release waits for the AbstractMemory release that contains it.
+- **The AbstractGateway integration** (the `abstractnote-seam` branch): binds the note tools to
+  each user's notebook, serves the note read API and lists the Note app. You need it only for the
+  gateway path; the headless notebook works without a gateway. The gateway must carry this seam
+  (`abstractgateway.abstractnote_seam`; the first gateway release with it is named at
+  AbstractNote's release): the `[gateway]` extra alone does not guarantee it, and
+  `abstractnote.gateway` refuses to import into a gateway without it, with one sentence.
+
+To run models locally on Apple silicon, add `pip install "abstractcore[apple]"` (MLX).
+
+## Quick start
+
+A headless notebook on this machine, no gateway and no model:
+
+```sh
+abstractnote capture "Met Dana about the LUT budget; she wants the Pareto by Friday." --notebook ~/notes
+abstractnote search "LUT budget" --notebook ~/notes
+abstractnote status --notebook ~/notes
+```
+
+Let a model understand the queued notes (entities, claims, tasks), then ask a question:
+
+```sh
+abstractnote process --local --notebook ~/notes --provider mlx --model mlx-community/Qwen3.6-35B-A3B-4bit
+abstractnote search "What does Dana want?" --effort standard --notebook ~/notes \
+    --provider mlx --model mlx-community/Qwen3.6-35B-A3B-4bit
+```
+
+A notebook is pinned to the embedding model that created it. Choose it on the first command
+(`--embed-base-url` and `--embed-model`, for example a local LM Studio embedding model) and give
+the same flags every time, or start with the built-in offline embedder and change later with
+`abstractnote rebuild --reembed`. See [docs/getting-started.md](docs/getting-started.md).
+
+Through a gateway, clients start the `note-capture` and `note-recall` flows with the gateway's
+runs API, and `POST /api/gateway/note/processor/ensure` creates the per-user processor that
+understands notes in the background. The getting-started guide walks through a private scratch
+gateway, the web app and the watch app.
+
+## Clients
+
+| Client | Where | What it does |
+|---|---|---|
+| Web app | [`web/`](web/) (`@abstractframework/note`) | Capture (a chat with attachments), Graph (entities and links through time), Remember (since you last looked, cue cards, ask by effort, then and now), Settings |
+| Apple Watch app | [`watch/apple/`](watch/apple/README.md) | Note, Ask, Today, Settings; watch-only, watchOS 26 or later |
+| Command line | `abstractnote` | Headless capture, search, processing, imports, rebuild, JSON output for scripts and agents |
+
+An iPhone app is planned ([`phone/iphone/`](phone/iphone/README.md)). Agents use the same note
+tools and flows, with the effort level as a parameter.
+
+## Documentation
+
+- [docs/README.md](docs/README.md): the documentation index
+- [Getting started](docs/getting-started.md): a headless notebook in five minutes, then the gateway path
+- [Architecture](docs/architecture.md): components, data plane, request lifecycles
+- [API](docs/api.md): runs API usage, note read API, note tools, Python API, CLI
+- [Data model](docs/data-model.md), [Cognition](docs/cognition.md), [Remembering](docs/remembering.md),
+  [Clients](docs/clients.md), [Importers](docs/importers.md)
+- [FAQ](docs/faq.md) and [Troubleshooting](docs/troubleshooting.md)
+- [Contributing](CONTRIBUTING.md), [Security](SECURITY.md), [Changelog](CHANGELOG.md),
+  [Acknowledgements](ACKNOWLEDGEMENTS.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).